DrawText

DrawText
Header:	QuickdrawText.h		Carbon status:	Supported

Draws the specified text at the current pen location in the current graphics port.

void DrawText (
    const void *textBuf, 
    SInt16 firstByte, 
    SInt16 byteCount
);

Parameter descriptions

textBuf

A pointer to a buffer containing the text to be drawn.

firstByte

An offset from the start of the text buffer (textBuf) to the first byte of the text to be drawn.

byteCount

The number of bytes of text to be drawn. Inside a picture definition, DrawText cannot have a byteCount greater than 255.

For 2-byte script systems, note that byteCount is the number of bytes to be drawn, not the number of glyphs. Because 2-byte script systems also include characters consisting of only 1 byte, do not simply multiply the number of characters by 2 to determine this value; you must determine and specify the correct number of bytes.

DISCUSSION

The DrawText function draws the text with the leftmost glyph at the current pen location, extending right. After QuickDraw draws the text, it sets the pen location to the right of the rightmost glyph.

QuickDraw temporarily stores on the stack all of the text you ask it to draw, even if the text is to be clipped. When drawing a range of text, it’s best to draw only what is visible on the screen. If an entire text string does not fit on a line, truncate the text at a word boundary. If possible, avoid truncating within a style run. You can determine the number of characters whose glyphs actually fit on the screen by calling the TextWidth function before calling DrawText.

If you specify values in the graphics port spExtra and chExtra fields to change the width of nonspace and space characters, both TextWidth and DrawText take these values into account.

For 1-byte complex script systems, DrawText substitutes the proper ligatures, reversals, and compound characters as needed.

For right-to-left text, such as Hebrew or Arabic, QuickDraw draws the final (leftmost) glyph first, then moves to the right through all the characters, drawing the initial (rightmost) glyph last.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.